home *** CD-ROM | disk | FTP | other *** search
/ Shareware Grab Bag / Shareware Grab Bag.iso / 007 / icondoc.arc / RUN.DOC < prev    next >
Text File  |  1985-09-30  |  8KB  |  265 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.    The Translation and Execution of Icon Programs under MS-DOS
  8.  
  9.  
  10.  
  11.    The program icont is a command processor for Version 5.9 of
  12. the Icon programming language.  It produces a file suitable for
  13. interpretation by the Icon interpreter.  The Icon translator is
  14. run in the form
  15.  
  16.         icont [ option ... ] file ... [-x] [arg ... ]
  17.  
  18. Translation consists of two phases:  translation and linking.
  19. During translation, each Icon source file is translated into an
  20. intermediate language; during linking, the intermediate language
  21. files are combined and a single output file is produced.  The
  22. output file from the linker is referred to as an interpretable
  23. file.  Unless the -o option is specified, the name of the result-
  24. ing interpretable file is formed by deleting the suffix of the
  25. first input file named on the command line.  If the -x option is
  26. used, the file is automatically executed by the interpreter and
  27. any arguments following the -x are passed as execution arguments
  28. to the Icon program itself.
  29.  
  30.    Files whose names end in .icn are assumed to be Icon source
  31. programs; they are translated, and the intermediate code is left
  32. in two files of the same name with .u1 and .u2 substituted for
  33. .icn.  The intermediate code files normally are deleted when com-
  34. pilation has finished.  Files whose names end in .u1 or .u2 are
  35. assumed to be intermediate code files from a previous translation
  36. (only the .u1 file should be named -- the .u2 file is assumed);
  37. these files are included in the linking phase after any .icn
  38. files have been translated.  A .u1 or .u2 file that is explicitly
  39. named is not deleted.  Icon source programs may be read from
  40. standard input.  The argument - signifies the use of standard
  41. input as a source file.  In this case, the intermediate code is
  42. placed in stdin.u1 and stdin.u2 and the interpretable file is
  43. stdin.
  44.  
  45.    The following options are recognized by icont.
  46.  
  47. -c        Suppress the linking phase.  The intermediate code
  48.           files are not deleted.
  49.  
  50. -o output Name the interpretable file output.
  51.  
  52. -s        Suppress any informative messages from the translator
  53.           and linker.  Normally, both informative messages and
  54.           error messages are sent to standard error output.
  55.  
  56. -t        Arrange for &trace to have an initial value of -1 when
  57.           the program is executed.  Normally, &trace has an ini-
  58.           tial value of 0.
  59.  
  60.  
  61.  
  62.  
  63.  
  64.                               - 1 -
  65.  
  66.  
  67.  
  68.  
  69.  
  70.  
  71.  
  72.  
  73. -u        Issue warning messages for undeclared identifiers in
  74.           the program.  The warnings are issued during the link-
  75.           ing phase.
  76.  
  77.    Icon has a number of memory regions related to the translation
  78. of programs.  These regions are large enough for most programs,
  79. but their size can be changed, if necessary, by the -S option,
  80. which has the form -S[cfgilrstCL] n, where the letter following
  81. the S specifies the region and n is the number of storage units
  82. to allocate for the region. The regions are:
  83.  
  84.      c  literal table
  85.  
  86.      f  field table
  87.  
  88.      g  global symbol table
  89.  
  90.      i  identifier table
  91.  
  92.      l  local symbol table
  93.  
  94.      r  field table for record lists
  95.  
  96.      s  string space
  97.  
  98.      t  tree space
  99.  
  100.      C  code buffer
  101.  
  102.      L  labels
  103.  
  104.    The environment variable IPATH controls the location of files
  105. specified in link directives. IPATH should have a value of the
  106. form p1:p2: ... : pn where the pi name directories.  Each direc-
  107. tory is searched in turn to locate files named in link direc-
  108. tives. The default value for IPATH is . , that is, the current
  109. directory.
  110.  
  111.    The interpretable file produced by the Icon linker is run by
  112. the program iconx.  For example, the command
  113.  
  114.         icont hello.icn
  115.  
  116. produces a file named hello that can be run by the command
  117.  
  118.         iconx hello
  119.  
  120.  
  121.    The phases also can be executed separately. For example,
  122.  
  123.         itran hello.icn
  124.         ilink hello.u1
  125.         iconx hello
  126.  
  127.  
  128.  
  129.  
  130.                               - 2 -
  131.  
  132.  
  133.  
  134.  
  135.  
  136.  
  137.  
  138.  
  139. is equivalent to
  140.  
  141.         icont hello.icn -x
  142.  
  143.  
  144.    Arguments can be passed to the Icon program by following the
  145. program name with the arguments.  Any such arguments are passed
  146. to the main procedure as a list of strings.
  147.  
  148.    When an Icon program is executed, a number of environment
  149. strings are examined to determine certain execution parameters.
  150. The values assigned to these strings should be numbers.  The
  151. environment strings that affect execution and the interpretations
  152. of their values are as follows:
  153.  
  154. TRACE     Initialize the value of &trace.  If this variable has a
  155.           value, it overrides the translation-time -t option.
  156.  
  157. NBUFS     The number of i/o buffers to use for files.  When a
  158.           file is opened, it is assigned an i/o buffer if one is
  159.           available and the file is not a console.  If no buffer
  160.           is available, the file is not buffered.  &input, &out-
  161.           put, and &errout are buffered if buffers are available.
  162.           The default number is 5.
  163.  
  164. NOERRBUF  If set, &errout is not buffered.
  165.  
  166. STRSIZE   The initial size of the string space, in bytes.  The
  167.           string space grows if necessary, but it never shrinks.
  168.           The default value is 10,240.
  169.  
  170. HEAPSIZE  The initial size of the heap, in bytes.  The heap grows
  171.           if necessary, but it never shrinks.  The default value
  172.           is 10,240.
  173.  
  174. NSTACKS   The number of stacks initially available for co-
  175.           expressions.  More are automatically allocated if
  176.           needed.  The default value is 2.
  177.  
  178. STKSIZE   The size of each co-expression stack, in words.  The
  179.           default value is 1000.
  180.  
  181. Files
  182.  
  183.    The following files are needed to translate and run Icon pro-
  184. grams:
  185.  
  186.         icont.exe        command processor
  187.         itran.exe        translator
  188.         ilink.exe        linker
  189.         iconx.exe        interpreter
  190.  
  191.  
  192.  
  193.  
  194.  
  195.  
  196.                               - 3 -
  197.  
  198.  
  199.  
  200.  
  201.  
  202.  
  203.  
  204.  
  205. References
  206.  
  207. An Overview of the Icon Programming Language, Ralph E. Griswold,
  208. Department of Computer Science, The University of Arizona, Sep-
  209. tember 1985.
  210.  
  211. The Icon Programming Language, Ralph E. Griswold and Madge T.
  212. Griswold, Prentice-Hall Inc., Englewood Cliffs, New Jersey, 1983.
  213.  
  214. Extensions to Version 5 of the Icon Programming Language, Ralph
  215. E. Griswold, Department of Computer Science, The University of
  216. Arizona, September 1985.
  217.  
  218. Bugs and Deficiencies
  219.  
  220.    Downward compatibility of interpretable files will not be
  221. maintained in subsequent releases of Icon.  No checks are per-
  222. formed to determine if the interpretable file and the interpreter
  223. are compatible.  Peculiar program behavior is the only indication
  224. of such incompatibility.
  225.  
  226.    Interpretable files do not stand alone; the Icon interpreter
  227. must be present on the system.  This implies that the interpreter
  228. is of the same version of Icon as the translator that produced
  229. the interpretable file.
  230.  
  231.    Because of the way that co-expressions are implemented, there
  232. is a possibility that programs in which they are used may mal-
  233. function mysteriously.
  234.  
  235.    Integer overflow on multiplication is not detected.
  236.  
  237.    If garbage collection fails, iconx may abort with an inap-
  238. propriate message.
  239.  
  240.    Stack overflow is not detected immediately and may generate
  241. odd messages.
  242.  
  243.  
  244.  
  245. Ralph E. Griswold
  246.  
  247. Department of Computer Science
  248. The University of Arizona
  249.  
  250. September 30, 1985
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.  
  262.                               - 4 -
  263.  
  264.  
  265.